jql
A JSON Query Language CLI tool built with Rust 🦀
📜 Core philosophy
- 📦 Stay lightweight
- 🎮 Keep its features as simple as possible
- 🧠 Avoid redundancy
- 💡 Provide meaningful error messages
- ↔️ Eat JSON as input, process, output JSON back
⚠️ Non-goal
This tool has absolutely no plan to be on par with jq
and such other similar CLI.
🚀 Installation
Alpine Linux
The package is maintained by @jirutka.
Archlinux
The AUR package is maintained by @barklan.
Cargo
Fedora
Homebrew
Nix
openSUSE
Manual installation from GitHub
Compiled binary versions are automatically uploaded to GitHub when a new release is made. You can install jql
manually by downloading a release.
🛠️ Usage
If you find some of the following examples confusing, please have a look at The JavaScript Object Notation (JSON) Data Interchange Format.
Root selection
"This is a valid JSON text with one value"
"This is a valid JSON text with one value"
Child selection
"yay!"
Index selection
7
Please note that the following is also valid:
7
You can also select a set of indexes:
Range selection
Please note that you can reverse it:
Bonus, you can do it again to get it back:
Please note that you can still access the children:
"Misty"
You can also use the start or the end position as a range selector:
Array selection
Please note that this is basically an alias for a full range selection:
Property selection
Property selection can also be used with indexes and ranges. Please note that in this case a remapping/transformation is applied to the JSON data:
This is pretty unusual, but it might help in some scenarios when e.g. one wants to extract some properties out of a complex JSON structure based on their order:
Multi-selection
Filter
You can also combine a filter with a child selection, a multi-selection and ranges at the same time:
Please note that you can combine filters to achieve the same result:
Flatten
Arrays
Objects
Lens
Lenses enable filtering an array of objects by key, key/value pair or a combination of both. Please
note that only number
, string
and null
primitive can be used as value.
Truncate
The truncate selector !
can be used to stop walking the children's values and to explore an unknown JSON file / structure.
Each child is then transformed into a JSON primitive for convenience, e.g.:
primitive | value | result |
---|---|---|
object | { "a": 1, "b": 2, "c": 3 } |
{} |
array | [1, 2, 3] |
[] |
string | "foo" |
"foo" |
number | 666 |
666 |
null | null |
null |
Special characters
In order to be fully compliant with JSON's object keys, jql
always expect selectors to be
double-quoted.
1337
"yeah!"
"yup, valid too!"
💻 Shell integration
How to save the output
How to read from stdin
|
Available flags 🤖
Help
Check
The command will return a matching exit code based on the validity of the JSON content or file provided. No selector is needed in this case!
Please note that this flag is exclusive.
From file
The command will reads the provided selectors from a file rather than from a command line.
Inlining the JSON output
Raw output
Use the raw-output
flag on a string selection to directly return the raw string without JSON double-quotes:
|
|
Streaming
Use the stream
flag to read a stream of JSON lines:
while ; do ; ; done |
while ; do ; ; done |
Please note that this option is only about reading valid JSON output streamed line by line (e.g. Docker logs with the --follow
flag). This is not an option to read an incomplete streamed content (e.g. a very large input)!
Version
🍿 Library
This crate is both a binary (the CLI tool) and a library that can be directly used https://docs.rs/crate/jql/.
⚡ Performance
Some benchmarks comparing a set of similar functionalities provided by this tool and jq are available here.